 Prev |
Print
This article describes the Sitecore Query syntax.
Sitecore Query uses a path notation, similar to XPath expressions, for addressing Items of a Sitecore content tree. The expression is evaluated to yield an Item set. In addition, a query expression may have predicates (filter expressions). For example, the expression Entry[@Title = 'Welcome to Sitecore'] refers to the Entry Items whose Title field is set to "Welcome to Sitecore".
Below are some common query expressions:
-
"/sitecore/content/Home"
Returns all items that are children to home.
- "/sitecore/content/home|/sitecore/system"
Yields children of home and system items.
- "query:/sitecore/content/home//*[@@templatename='Document']"
Returns all items that have home as ancestor and have Document as template name.
Notes :
Item names in the path expression are not case sensitive (/sitecore/content/Home/Products has the same result as /sitecore/content/home/products).
You can use escaped double quotes instead of single quotes. This is especially useful in case a search criterion contains single quotes. For example:
"/sitecore/content//*[@title=\"Simple'value\"]"
Items with dashes in names (“-”) should be included in “#” symbols. Please use such syntax: /sitecore/content/Home/#About-us#. Otherwise you may get the following error: Invalid lookup source "/sitecore/content/TestSiteB/Home/About-us": End of string expected at position 38. Also, an item name should be included in “#” symbols if it contains “and” or “or” word and is used before “//*” symbols. For example: "/sitecore/content/Home/#news and events#//*". Item names that start with one or more digits should also be included in “#” symbols. For example: "/sitecore/content/Home/News/#2012#/January".
We will use a sample package to illustrate the explanations below.
Download the sample package . Note: we recommend that you install the package on a clean Sitecore installation.
The package contains a content tree shown in the picture below:
The package also includes the following templates: Product, Shape and Query Test.
The Query Test Item is based on the Query Test template which contains a multilist field. This field is used to test the queries given in the present article.
3.1. Basic Query Expressions
Below is a list of basic expressions used in the query paths:
| Expression | Description |
| / | Selects from the root Item |
| // | Selects Items from all descendants of the context Item that match the selection |
| .. | Selects the parent of the current Item |
| @ | Selects fields (please refer to the Attributes section for details) |
| @@ | Selects attributes (please refer to the Attributes section for details) |
Examples:
-
/sitecore/content/Home/Products
Output:
- query:/sitecore/content/Home/Products
Output:
- query:/sitecore/content/Home//Circle
Output:
- query:/sitecore/content/Home//Circle/..
Output:
The pipe (“|”) separator is used to select several paths in one expression. For instance:
query:/sitecore/content/Home/Products|/sitecore/content/Home//Circle/..|/sitecore/content/Home//Circle
Output:
Predicates are used to find a specific Item or an Item that contains a specific value.
Predicates are always embedded in square brackets. Below is the description of two groups of predicates available in Sitecore – Attributes and Functions.
3.2. Attributes
Attribute: [@fileldname]
Description: Item field name.
Query Example:
query:/sitecore/content/Home/*[@Title = 'Welcome to Sitecore']
Returns Items which have the value of the field 'Title' set to 'Welcome to Sitecore'. The search is performed among the children of the Home Item.
Note : Use the database field values when using fields in your query expressions. Read more about how field values are stored in the database.
query:/sitecore/content/Home/Products/Hammer[@Available = '1']
Returns all Hammer named Items which have the value of the checkbox field 'Available' set to '1'.
Attribute: [@@name]
Description: Item name. Case sensitive.
Query Example:
query:/sitecore/content/Home/Products/*[@@name = 'Hammer']
The search is performed among the children of the Products Item.
Attribute: [@@key]
Description: Item name lowercased. For example: [@@key = 'item'] will match iTEm and Item. Note: the key must be in lowercase.
Query Example:
query:/sitecore/content/Home/Products/*[@@key = 'hammer']
The search is performed among the children of the Products Item.
Attribute: [@@templateid]
Description: Item Template ID.
Query Example:
query:/sitecore/content/Home//*[@@templateid = '{F348C2A0-73B8-4AF4-BD9E-2C5901908369}']
Returns all descendants of the Home Item based on the template with the mentioned ID. 
Attribute: [@@templatename]
Description: Item Template name. The value is case sensitive.
Query Example:
query:/sitecore/content/Home//*[@@templatename = 'Shape']
Returns all descendants of the Home Item based on the Shape template.
Attribute: [@@templatekey]
Description: The template name in lowercase.
Query Example:
query:/sitecore/content/Home//*[@@templatekey = 'product']
Returns all descendants of the Home Item based on the Product template.
Attribute: [@@id]
Description: Item ID.
Query Example:
query://*[@@id = '{787EE6C5-0885-495D-855E-1D129C643E55}']
Searches through the entire content tree and returns an Item with the mentioned ID.
Other Examples:
Query expressions may be quite complex:
query:/sitecore/content/Home//*[@@id='{D394CCA7-C88B-418C-8B2B-AA97AA52EE14}' or @@key = 'stylish bag' or @@name = 'Hammer']
Result: 
query:/sitecore/content/Home//*[@Text='Bargain Price' and @Available='1']
Result:
3.3. Functions
Sitecore query functions make it possible to perform Boolean operations with Items in query expressions and apply extra conditions to the query.
Function: contains(s1:string, s2:string):bool
Description: Indicates whether s1 contains substring s2. The comparison is case sensitive.
Query Example:
query:/sitecore/content/Home/Products/*[contains(@Text, 'Bargain')]
Returns child Items of the Products Item which contain 'Bargain' fragment in the Text field.
Function: startswith(s1:string,s2:string):bool
Description: Indicates whether s1 starts with substring s2. The comparison is case sensitive.
Query Example:
query:/sitecore/content/home//*[startswith(@@name, 'S')]
Returns child Items of the Home Item whose name starts with S.
Function: endswith(s1:string,s2:string):bool
Description: Indicates whether s1 ends with substring s2. The comparison is case sensitive.
Query Example:
query:/sitecore/content/home//*[endswith(@@name, 's')]
Returns child Items of the Home Item whose name ends with s.
Function: last():int
Description: Returns the index of the last Item in the list of children.
Query Example:
query:/sitecore/content/home/Products/*[last()]
Returns the index of the last child Item under the Products Item.
Function: not(condition:bool):bool
Description: Returns the parameter’s opposite value.
Query Example:
query:/sitecore/content/Home/Products/*[not(contains(@Text, 'Bargain'))]
Returns child Items of the Products Item whose text field doesn’t contain the string Bargain.
Function: position():int
Description: Returns the position of the context Item.
Query Example:
query:/sitecore/content/Home/Products/*[position() >= 2]
Returns child Items of the Products Item whose index is more than or equal to 2.
3.4. Axes
The axis component of a query determines the direction of the node selection in relation to the context node. An axis can be thought of as a directional query.
Please follow the link below for more information about Axes in Sitecore:
http://sdn.sitecore.net/Developer/Sitecore%20and%20XSL/Axes.html
| ancestor | Returns all the ancestors of the context Item (same as XPath) |
| ancestor-or-self | Returns the context Item and all the ancestors of the context Item (same as XPath) |
| child | (/*) Returns all the children of the context Item (same as XPath) |
| descendant | (//*) Returns all the descendants of the context Item; a descendant is a child or a child of a child and so on (same as XPath) |
| descendant-or-self | Returns the context Item and all the descendants of the context Item (same as XPath) |
| following | Returns all the following siblings of the context node (same as following-sibling in XPath) |
| parent | (..) Returns the parent Item of the context Item (same as XPath) |
| preceding | Returns all the preceding siblings of the context Item (same as preceding-sibling in XPath) |
| self | (.) returns the context Item (same as XPath) |
| [int index] | Returns the child Item with the mentioned index |
Examples:
1) query:/sitecore/content/Home/Products/Documents/parent::*/child::*
Result
: returns all children of the parent Item of the Documents Item.
query:/sitecore/content/Home//*[@@name='Jacket']/ancestor-or-self::*
Result
: returns all ancestors of the Jacket Item and the Jacket Item itself.
2) query:/sitecore/content/Home/*[@@name='Products']/child::*
Result
: returns children of the Products Item.
3) query:/sitecore/content/Home/descendant::*[@@name='Documents' or @@name = 'Shapes']
Result : returns Documents and Shapes Items if they are present among the descendants of the Home Item (the functionality of the Axis expression here is the same as that of the //* expression).
4) query:/sitecore/content/Home//*[@@name='Stylish Bag' or @@name = 'Shapes']/following::*
Result
: returns all Items that follow the Stylish Bag Item and Shapes Item.
5) query:self::
Result
: returns the Query Test Item, which appears to be the context Item.
6) query:/sitecore/content/Home/*[3]
Result
: returns the Item under the Home Item whose index is equal to 3.
3.5. Operators
Below is a list of operators that can be used in Sitecore Query expressions:
| Operator | Description | Example | Return value |
| | | Contracts two Item-sets | //*/Products|//*/Shapes | Returns children of Products and Shapes Items |
| + | Addition | 6 + 4 | 10 |
| - | Subtraction | 6 - 4 | 2 |
| * | Multiplication | 6 * 4 | 24 |
| div | Division | 8 div 4 | 2 |
| = | Equal | position()=3 | true if position() is 3, false otherwise |
| != | Not equal | position()!=3 | False if position() is 3, true otherwise |
| < | Less than | position()<4 | true if position() is less than 4 |
| <= | Less than or equal to | position()<=4 | true if position() is less than or equal to 4 |
| > | Greater than | position()>4 | true if position() is greater than 4 |
| >= | Greater than or equal to | position()>=4 | true if position() is greater than or equal to 4 |
| or | or | position()=3 or position()=4 | true if position() is 3 or 4, false otherwise |
| and | and | position()>3 and position()<7 | true if position() is between 3 and 7, false otherwise |
| mod | Modulus (division remainder) | 5 mod 2 | 1 |
Examples:
query:/sitecore/content/home/*[(2+3) div 2 - 1]
query:/sitecore/content/Home/*[3 * 2 - 6 div 2]
query:/sitecore/content/home/*[(@@name='Item1' or @@name='Item2') and position()>= 1 and position() < 5 and position() != 3]
query:/sitecore/content/Home/Products/Documents/Old Document/ancestor-or-self::*|self::
Prev